home *** CD-ROM | disk | FTP | other *** search
/ BMUG Revelations / BMUG Revelations.toast / Programming / Programming Languages / Harvest C / Read Me < prev    next >
Text File  |  1991-10-14  |  17KB  |  395 lines
  1. 1
  2.  
  3.  
  4. Release Notes
  5. Harvest C, Shareware version
  6. Release 1
  7. 14 October 1991
  8.  
  9. Copyright 1991 Eric W. Sink
  10. All Rights Reserved.
  11.  
  12. Harvest C is a shareware C compiler for the Macintosh.  An integrated development 
  13. environment, Harvest C is intended to be compatible with the MPW C compiler.  Harvest 
  14. C compiles (almost) all the same extensions to ANSI C which are supported by MPW C. 
  15. Harvest C also generates object files which are compatible with MPW.
  16.  
  17. NOTICE
  18.  
  19. Throughout this notice, the "SOFTWARE" refers to this version (release 1, 14 October 1991) and only 
  20. this version of Harvest C, including all accompanying documentation, notices, source files, executables, 
  21. and release notes,  and no other releases or products.  The following statements reflect the legal conditions 
  22. of the use of this SOFTWARE.  If the terms expressed below are unacceptable to you, then you should not 
  23. use the SOFTWARE.
  24.  
  25. 1. The SOFTWARE is Copyright 1991 Eric W. Sink, All Rights Reserved.  Harvest C is NOT public 
  26. domain.
  27.  
  28. 2. You are explicitly granted the right to use and distribute the SOFTWARE freely and publicly, as long as 
  29. all copyrights, notices, release notes, documentation, source files and executables are included and 
  30. unchanged from the original release made by the author.  You may not distribute modified copies of the 
  31. SOFTWARE.
  32.  
  33. 3. You may not falsely represent the author or copyright holder of the SOFTWARE, either by omission or 
  34. misrepresentation.  The author of this SOFTWARE is Eric W. Sink.  Currently the copyright holder is 
  35. also Eric W. Sink.
  36.  
  37. 4. The SOFTWARE is referred to as "shareware".  Because the term "shareware" does not have a strict legal 
  38. definition, the following clarifications make the terms more specific :
  39.  
  40.    a. You may register yourself (and are encouraged to do so) as a user of the SOFTWARE, by sending a fee 
  41. of US $25 to :
  42.         Eric W. Sink
  43.         1014 Pomona Drive
  44.         Champaign, Illinois  61821
  45.  
  46.    b. You are under no legal obligation to register.  In general, it is recommended that you register and pay 
  47. for any shareware which you use.  This notice is merely intended to make the legal aspect of shareware 
  48. registration more specific for this SOFTWARE.
  49.  
  50. 5. The SOFTWARE is provided with absolutely NO WARRANTY, under any conditions.  In no case will 
  51. the author, copyright holder, or any distributor be in any way liable for any damages or difficulties of any 
  52. kind, either directly or indirectly caused by any kind of use of this SOFTWARE.  The author, copyright 
  53. holder and/or distributor of this SOFTWARE make no legal guarantees with respect to the usability of this 
  54. SOFTWARE, support of the SOFTWARE, or future releases of the SOFTWARE.
  55.  
  56. ---------- End of NOTICE ----------
  57.  
  58. FUTURE DIRECTIONS
  59.  
  60. This shareware version of Harvest C is being released to fill a perceived need for a freely 
  61. distributable C compiler for the Macintosh.  I intend to maintain it, and make subsequent 
  62. releases with bug fixes.  Future  shareware releases will not offer substantially more 
  63. functionality.  It is my intent to offer a commercially available version in the near future, 
  64. with the following  features :
  65.  
  66.     • 68020, 68881 code generation
  67.     • support for > 32k of global data
  68.     • precompiled headers
  69.     • SADE support
  70.     • optional 16/32 bit ints
  71.     • inline assembler
  72.     • more complete documentation
  73.     • increased speed
  74.     • reporting of software metrics
  75.     • support for object oriented programming
  76.     • full source code to the compiler included
  77.     • better code generation
  78.     • better linking
  79.     • full System 7 friendliness
  80.  
  81. Most of the above is already written.  My goal is provide Macintosh users with a 
  82. reasonably priced, full featured C development system, with source code.
  83.  
  84. REGISTRATION
  85.  
  86. You are encouraged to register yourself as a user, as described above.  
  87. Registered users will receive a discount on purchase of the commercial 
  88. version when it is released.  In addition, registered users will obtain 
  89. my attention much faster with respect to questions, fixes, desired 
  90. features and the like.  You may register yourself by supplying the 
  91. following information :
  92.  
  93. Name:
  94. Address (city, state, zip, and country):
  95. Phone (optional):
  96. email address (if you have one):
  97. Age (optional):
  98.  
  99. Suggestions for improvements:
  100.  
  101. Enclose a check for US $25 to :
  102.  
  103.     Eric W. Sink
  104.     1014 Pomona Drive
  105.     Champaign, Illinois  61821
  106.  
  107. I will acknowledge all registrations.
  108.  
  109.  
  110. CONTACTS
  111.  
  112. You are encouraged to contact me with any questions, comments, suggestions 
  113. or complaints.  You may reach me by electronic mail (USENET,Internet) at
  114.  
  115. e-sink@uiuc.edu
  116.  
  117. or by US mail at
  118.  
  119. Eric W. Sink
  120. 1014 Pomona Drive
  121. Champaign, Illinois  61821
  122.  
  123. I am not currently on AppleLink or CompuServe.
  124.  
  125. USING HARVEST C
  126.  
  127. Harvest C includes a built-in text editor.  This editor offers MINIMAL functionality, and is 
  128. not intended to be used as a principal programmer's editor.  The Harvest C editor does not 
  129. support, tabs, undo, multiple fonts, searching, macros, or files longer than 32000 
  130. characters.  (For general purpose editing, I recommend the use of Alpha, an excellent 
  131. shareware programmer's editor, widely available at ftp sites.)  In any case, you may use 
  132. the text editor in the normal way, in conjunction with the File and Edit menus.
  133.  
  134. The Options menu allows control over some of the features of Harvest C.  Some of the 
  135. options are not enabled in the shareware version.  Harvest C stores its configuration in a 
  136. file called "Harvest C Options", in the System Folder.  It is necessary to inform Harvest C 
  137. of the locations of your include files, and libraries (see below).  You may specify these 
  138. using the entries under the Options menu.  Harvest C maintains the notion of an 
  139. "Application directory".  This is the directory in which you do most of your work.  This 
  140. may be set as an option as well.  You may (and should) save these choices as the defaults 
  141. by using the Save Defaults entry.  Harvest C reads the "Harvest C Options" file from 
  142. the System Folder when the application is opened.  If it has trouble reading the file, it 
  143. initializes all options to a set of reasonable defaults, and beeps.  This beep is to let you 
  144. know that the current option defaults are not yours, and that you should select the defaults 
  145. you prefer and save them.  Harvest C should beep the first time you run it.
  146.  
  147. The Options menu has three hierarchical menus which allow a number of different 
  148. settings.  The most important for the shareware version is the Warnings menu.  This 
  149. menu allows you to turn each of the various warnings on or off.  A check mark appears 
  150. next to the warnings which are active.
  151.  
  152. The Project menu allows compilation.  You may compile a single file using the 
  153. Compile entry.  Execution of a Harvest C build script is done with the Build entry.  
  154. User specified linking can be accomplished with the Link entry.
  155.  
  156. Compile...
  157. This option simply allows you to compile a single file.  Harvest C presents a file dialog, 
  158. asking you to specify which file you wish to compile.  The corresponding object file is 
  159. created, and user information is displayed in a new text window.
  160.  
  161. Build...
  162. Build scripts are the equivalent of Makefiles in MPW, and Project files in Think C.  A build 
  163. script describes an entire project by listing the files and libraries which are to be included in 
  164. the project.  Harvest C build scripts are very flexible, easily allowing any combination of 
  165. compiler options for any file or set of files.  Upon selecting this option, Harvest C presents 
  166. a file dialog, asking you to specify a build script.  You must create your build script by 
  167. hand, but fear not, it is not difficult, and a future version will have the ability to create it for 
  168. you.
  169.  
  170. Format of Build files
  171.  
  172. Each line of a build file may contain zero or more options, and zero or more filenames.  
  173. Filenames are assumed to be things which should be linked into the final application.  
  174. Filenames ending in '.c' are compiled.  Options which appear on the same line as one or 
  175. more filenames are in effect for only those files.  Options which appear alone (except for 
  176. preprocessor definitions) are in effect for the remainder of the build.  Options are specified 
  177. in an MPW like format.  On a given line, all characters after a cross hatch character (#) are 
  178. ignored (for commenting).  Furthermore, any blank line causes execution of the script to 
  179. cease (i.e. blank lines are not allowed in the middle of the file).  Legal options are (for the 
  180. shareware version)
  181.  
  182.     -nolink    Compiles but does not link
  183.     -WonXXX    Turn warning number XXX on
  184.     -WoffXXX    Turn warning number XXX off
  185.     -progress    Turns progress reporting on
  186.     -signedchar    Toggles the sign of char types
  187.     -w        No warnings
  188.     -U$$$$    #undefs $$$$
  189.     -D$$$$=@@    #define $$$$ @@
  190.     -o name    Sets output file name (no spaces allowed)
  191.     -c ????    Sets output file creator signature (no quotes, i.e. no spaces)
  192.  
  193. When executing a build script, Harvest C looks in the standard application directory for C 
  194. source files needing compilation.  For object files needed for the link, Harvest C looks first 
  195. in the application directory, then in the standard library directory.
  196.  
  197. Link...
  198. Using this option you may link any group of files you like.  Harvest C displays a dialog for 
  199. selection of object files for the link.  Select as many as you like, clicking the Add button 
  200. after each one.  After the last file, click the Done button.  Then Harvest C asks you (with 
  201. a dialog) for the destination of the link output (the application you will be generating).  
  202. User information from the link appears in a new text window.
  203.  
  204. Warnings
  205.  
  206. This version of Harvest C supports the following warnings.  Warnings appearing in bold 
  207. are turned on by default.
  208.  
  209. 1        Empty expression stmt  
  210. 2        Multi-character constant
  211. 3        Redundant cast
  212. 4        Equivalence test of floating type
  213. 5        Discarded function result
  214. 6        Assignment as if conditional
  215. 7        Non-void function has no return statement
  216. 8        Constant expression as if condition
  217. 9        Comparison of pointer and integer
  218. 10        Assignment of nonequivalent type to a pointer
  219. 11        Return of nonequivalent type to a pointer
  220. 12        Pass of nonequivalent type to a pointer
  221. 13        Constant expression as switch condition
  222. 14        Constant expression as while loop condition
  223. 15        Constant expression as do-while loop condition
  224. 16        Constant expression as for loop condition
  225. 17        Switch expression not of integral type.
  226. 18        Volatile is not handled by this compiler
  227. 20        Unused variable: 
  228. 21        Dead code
  229. 22        Implicit decl : 
  230. 23        Re#definition : 
  231. 24        Possible nested comment
  232. 26        goto statement found
  233. 27        Multiple function returns
  234. 28        Empty compound statement
  235. 29        Missing function return type - default to int
  236. 30        Trigraph found
  237. 32        pascal keyword found
  238. 34        Semicolon after function body
  239.  
  240. Miscellaneous
  241.  
  242. It is possible to abort compilation by pressing and holding Command-period.
  243.  
  244. Pragmas
  245.  
  246. Harvest C supports two pragmas from MPW C, parameter (for use by the include files) 
  247. and segment.  In other words, it does not support once, trace, processor, 
  248. force_active, push, or pop (or any others which I missed), yet.
  249.  
  250. The parameter pragma should be of no use to normal programmers.
  251.  
  252. The segment pragma is used for code resource segmentation :
  253.  
  254. #pragma segment Foo
  255.  
  256. means that all subsequent code goes in the segment named Foo.
  257.  
  258. Required Memory
  259.  
  260. Harvest C likes to have a lot of memory.  This is due in part to some inefficient memory 
  261. management, and should be improved in the future.  Meanwhile, try to keep your C source 
  262. files small.  Keep in mind, that even a tiny C source file effectively becomes huge if it 
  263. #includes several standard header files.
  264.  
  265.  
  266. Interfaces & Libraries
  267.  
  268. In order for your program to be linked to form an application, you must link with some 
  269. standard libraries.  These libraries allow access to Toolbox routines, handle initialization of 
  270. global variables, and things like that.  Furthermore, use of these libraries will generally 
  271. require that you use the interface (or header) files which accompany them.
  272.  
  273. You must obtain Apple's headers and libraries in order to use Harvest C.  I  do not yet have 
  274. legal permission to distribute them.  They are sold from the Apple Programmers and 
  275. Developers Association, and are called "MPW Toolbox Interfaces and Libraries v. 7.0", 
  276. product number M0615LL/B, at a cost of $40.  You may reach APDA at :
  277.     APDA
  278.     Apple Computer, Inc.
  279.     20525 Mariani Avenue
  280.     Mail Stop 33G
  281.     Cupertino, CA 95014-6299
  282.  
  283. You may also obtain the necessary headers and libraries by anonymous ftp from 
  284. ftp.apple.com.  You need the file cincludes-mpw3-2.hqx, in directory 
  285. /dts/mac/system7/7.0.mpw/interfaces.  This is a Binhexed, Stuffit archive 
  286. containing the header files.  In addition, you need the files clibraries.hqx and 
  287. libraries.hqx, stored in directory /dts/mac/system7/7.0.mpw/libraries.  
  288. Obtaining the files by anonymous ftp is not difficult.  You must first connect with Apple's 
  289. computer, by typing the following at the shell prompt of your UNIX system.
  290.  
  291. ftp ftp.apple.com
  292.  
  293. You should see something like
  294.  
  295. 220 bric-a-brac.apple.com FTP server (IG Version 5.90 (from 
  296. BU, from UUNET 5.51)...
  297.  
  298. Name (bric-a-brac.apple.com:yourlogin): 
  299.  
  300. Enter your name as anonymous (don't misspell it), and enter your full email address as 
  301. the password.  Then change to the proper directory by typing
  302.  
  303. cd /dts/mac/system7/7.0.mpw/interfaces
  304.  
  305. and obtain the interfaces by entering
  306.  
  307. get cincludes-mpw3-2.hqx
  308.  
  309. Then, 
  310.  
  311. cd /dts/mac/system7/7.0.mpw/libraries
  312.  
  313. and obtain the interfaces by entering
  314.  
  315. get clibraries.hqx
  316. get libraries.hqx
  317.  
  318. Enter quit to terminate your ftp connection.
  319.  
  320. Sample Programs
  321.  
  322. This release of Harvest C shareware comes with 2 sample programs.  Sample1 is truly 
  323. trivial.  It simply does some math calculations and beeps three times.
  324.  
  325. Sample2 is still not very complex, but it does create and manage a menu, allowing the user 
  326. to quit or use desk accessories.  Sample2 has two C source files, called Sample2a.c and 
  327. Sample2b.c.  Sample2a.c is very large, and Harvest C may require a large amount of 
  328. memory to compile it.  See the problems section below for comments about hogging 
  329. memory.
  330.  
  331. "I'm lost - what does all this mean ?"
  332.  
  333. This informational file is not intended to be full documentation.  I have made countless 
  334. assumptions about the experience of the reader.  If you are totally lost and do not 
  335. understand the terms of this document, be advised that I am preparing better 
  336. documentation.  In addition, feel free to contact me by electronic mail if you have any 
  337. questions.  I will accept questions from anyone, but I will respond to my registered users 
  338. first.
  339.  
  340. Keep in mind that even the finest documentation for this product would not be a tutorial for 
  341. the C language.  There are some good books on C available.  Better documentation would 
  342. include a list of them here.
  343.  
  344. If you are a relatively experienced C user and want to know specific details about how 
  345. Harvest C handles a certain situation, the only answer I have for you now is : "It works 
  346. just like MPW C".  This is undoubtedly not always true, but it is the ideal I want to strive 
  347. for.  I have written Harvest C to be compatible with MPW in almost every way.  This does 
  348. NOT make Harvest C just as good as MPW C, just compatible.  More specifically, MPW 
  349. C is currently faster and more reliable, produces better code, handles the comp data type, 
  350. does precompilation of headers, and supports the "32 bit everything" architecture.  My goal 
  351. is to make Harvest C a highly competent system in its own right, but I do not plan on 
  352. attempting to eliminate any of existing products, which are of excellent quality.
  353.  
  354. CURRENT PROBLEMS
  355.  
  356. As no software is bug free, and compilers are particularly prone to problems, I will not be 
  357. so foolish as to claim that Harvest C is perfect.  I do want to hear of any problems you 
  358. may have.  Please report difficulties to me so I can make bug fixes.  I plan to make 
  359. subsequent releases to fix problems.  The following items are already known, and I plan on 
  360. correcting them :
  361.  
  362. 1. The compiler is slow.  Building Sample2 on a Mac SE (System 7 with 4 MB) takes 
  363. roughly 9 minutes 20 seconds.  On a Mac IIci (System 7, 5 MB), it takes 1 minute 32 
  364. seconds.  On that same Mac IIci, MPW compiles and builds Sample2 in 31 seconds.
  365.  
  366. 2. Documentation is poor, almost nonexistent.
  367.  
  368. 3. Handling of errors is poor.
  369.  
  370. 4. The editor is very poor.  I have no plans of improving this, but I do plan to integrate 
  371. Harvest C with another editor, using System 7 IAC.
  372.  
  373. 5. Needs System 7 friendliness (Balloon help and Apple Events).  Compatibility with 
  374. virtual memory or 32 bit mode is unknown.
  375.  
  376. 6. Harvest C currently does not support the MPW comp data type
  377.  
  378. 7.  The reliability of SANE floating point math is not fully known.  It has not been 
  379. extensively tested.  Floating point math generated for the 68881 (not available in the 
  380. shareware version) has been tested more extensively.
  381.  
  382. 8.  Harvest C does not support printing.
  383.  
  384. 9.  The Harvest C Linker is not very smart.  It produces bloated applications.  Better 
  385. performance will be available in the commercial version.
  386.  
  387. 10.  Harvest C is somewhat of a memory hog.  The efficiency of its memory usage will be 
  388. cleaned up as the program matures.  This should speed up compilation as well.
  389.  
  390. 11.  Harvest C sometimes produces code which is truly inane.  I know about it, and I am 
  391. working on it.  I certainly welcome technical suggestions from any users (many of which I 
  392. know are far wiser than I).  I don't have too much difficulty looking at the Harvest C 
  393. output and seeing obvious problems, but I still welcome your ideas.
  394.  
  395.